MaxZip: A Macintosh interpreter for Z-code text adventures
<http://www.eblong.com/zarf/maxzip.html>
by Andrew Plotkin (erkyrath@netcom.com)
based on ZIP V2.0.7 by Mark Howell (howell_ma@movies.enet.dec.com)
There are a number of good Mac Z-code interpreters floating around -- notably Matthew Russotto's port of ZIP, and Greg Ewing's MacZeX. I would love to say that MaxZip is not based on any lack on their part. But... oh well. :-)
Basically, I got tired of not having true Macintosh convenience. I want copy and paste, scrolling, proportional fonts, resizable windows, command history, and macros. Well, I made all of that work under X windows with my XZip interpreter, so you think I'd be satisfied, right? Not on the Mac. I want double-clicking to work right. All the time. I want to be able to generate stand-alone games and take them apart as easily.
Here's the result.
◊ Running MaxZip
For those of you that came in late, MaxZip is not a game. It is an interpreter for Z-code, the low-level language developed by Infocom for writing their text adventures in. Infocom is dead and gone (pay no attention to the travesty behind Activision's curtain), but their language lives on, and people are still developing games for Z-code interpreters.
What this means is, you can't use MaxZip by itself. You need a Z-code file. (The canonical collection is available by FTP to ftp.gmd.de, in /if-archive. You will also find there Graham Nelson's compiler, Inform, which is what all those people are developing Z-code games with. )
If, however, you just got this application and it did start a terrific text adventure all by itself, you must be running a stand-alone game created with MaxZip. In which case, kill this window and play already. If you really want to know more, read the section “Unbound and stand-alone MaxZip”.
◊ Commands and controls
It's a Mac program. It acts like one. (I'll admit that I haven't put in drag-and-drop editing... yet.)
The keyboard commands are astonishingly flexible, because MaxZip is the estranged offspring of XZip, an X windows program whose interface is a bastard child of ATK, which is itself an illegitimate by-blow of the early Macintosh with a great deal of Emacs grafted on in early adulthood. Deal with it. Sadly, there is no way to take advantage of all that flexibility. Maybe next version.
The only unusual commands are up-arrow and down-arrow, which scroll up and down in the command history (rather than moving the insertion bar, as you might expect.)
The other obscure one is shift-cmd-Q (or hold down shift while selecting the “Quit” menu option.) This quits the game immediately, bypassing any “Are you sure?” prompts and score displays that the game may provide.
MaxZip supports macros — you can define up to ten different chunks of text, and then paste any of them with a single command key. To define a macro, highlight a block of text, and then hit cmd-D followed by cmd-1 (or any other digit from 0 to 9.) To paste that macro back in, hit cmd-1 (or whichever digit you chose.) Pull down the “Macros” menu to see the macros you have defined.
◊ Preferences
There are several pages of preferences, most of which are fairly obvious. Hit “Apply” to apply the preferences to the game (if a game is running); “Ok” to apply the preferences and dismiss the preferences window; and “Cancel” to cancel. Note that the same preferences apply to all MaxZip games, including stand-alone games.
• Story window preferences: You can set the left/right margin, the top/bottom margin, and the space between lines (all measured in pixels). You can also set whether the text is full-justified, and what style your inputs are displayed in.
• Status window preferences: The status window size is measured in characters. (If you change the size after starting a game, the status window will not change; Z-code games don't like the status window to change in mid-game. The changes will take effect at the beginning of the next game.) “Window Resizes Dynamically” causes the status window to resize according to the game's desires. You can set whether the status window resizes normally (top edge remains in place) or upward (bottom edge remains in place); you can also set the window to move to the front when it expands, and to the back when it contracts. (This sounds goofy, but works awfully nicely.) The “Box Quotes Clear Automatically” option causes pop-up quotes (such as in Trinity and Curses! ) to vanish the next time you hit Enter.
• Fonts preferences: This somewhat confusing page lets you control which Macintosh fonts are used to display the eight notional Z-machine fonts. (The eight combinations of unbold/bold, unitalic/italic, and proportional/fixed-width. Actually there's also non-reverse/reverse, but MaxZip assumes that reverse fonts look the same as non-reverse fonts.) Pick one of the eight, and then set the font, size, and attributes.
Note: it is very important that all the fixed-width fonts really be the same width! If you violate this rule, the status window will be a mess and probably drop characters. Use a single font such as Monaco, and if you turn on “bold”, turn on “condensed” too. (A warning indicator will appear if you violate this rule.)
• Colors preferences: This page lets you control the colors of the MaxZip windows. Click on a color patch to bring up a standard color picker dialog. You can set the general foreground and background colors, or set the (foreground) color of each of the eight fonts separately. (Reverse fonts are drawn with the general background color on a field of that font's individual color.) The reset buttons return to the default colors: the default background is white, the default foreground is black, and the default for each font folor is whatever the foreground color is.
If your Mac supports color, but has a black-and-white monitor, you can set these preferences, but the results will be reduced to black or white. About all you can usefully do is switch black and white. If your Mac does not support color at all, this page of preferences is inactive, and you will always have the default colors. Sorry.
• Interpreter preferences: You can set how many commands are stored in the command history. (Changes to this preference will not take effect until the next game starts.) You can also set the size of the story buffer (how many characters are stored) and the slack (how many characters will be stored past the size limit before MaxZip deletes a chunk off the top. This is only important because deleting a chunk is a little slow, so you don't want to set the slack too low.) The next preference controls whether the “Hit a key to continue” message appears after each page of text in the story window. You can control the feature which lets you put a brief comment in each saved-game file, and see the comments as you navigate around the restore-game dialog. (This is a slightly goofy feature, and a little slow on older Macs, so turn it off if you don't want it.) Finally, you can control how MaxZip reports certain errors which occur in some games.
◊ Unbound and stand-alone MaxZip
MaxZip can exist by itself (“unbound”). In this state, it works like most other Mac ZIP interpreters. First you import a Z-code file, then you play. MaxZip tries to make this easy for you, in the following ways:
• If you have a Z-code file whose type is 'ZCOD', you can drag it onto MaxZip to start it up.
• If you have a Z-code file whose type is 'ZCOD' and whose creator is 'mxZR' (MaxZip's creator code), you can start it up simply by double-clicking it.
• If you have a Z-code file with a different type (say, because you just downloaded it), you can import it by starting MaxZip and choosing the “Import Z-Code File...” menu option.
• If you have a saved-game file whose type is 'IFZS', you can drag it onto MaxZip, or just double-click it if its creator is 'mxZR'. Since a saved game is meaningless without a Z-code file, you will immediately be prompted for a Z-code file to play; you must pick the one which generated that save file.
It is also possible to generate a stand-alone (“bound”) MaxZip application, which contains a Z-code file embedded in it. This is even easier to use:
• Double-clicking the stand-alone game starts it up immediately.
• Double-clicking a saved-game file produced by the stand-alone game starts the game and restores that saved game immediately.
There are some other advantages to this system:
• A stand-alone game has its own creator code, so it can have its own icon and provide an icon for its saved games.
• If you have a stand-alone game, you can write out its Z-code with the “Export Z-Code File...” menu option. This produces a standard machine-independent Z-code file, which you can upload to other systems.
• You can also build an unbound MaxZip application from a stand-alone one, with the “Build Unbound MaxZip...” menu option. This means that someone who receives a stand-alone game can go on to use MaxZip with all her Z-code files.
◊ Creating a stand-alone game
• Start MaxZip (you've already done that).
• You can import or double-click a Z-code file, and use the “Build Stand-Alone Game...” menu option. Or, if you don't feel like looking at the beginning of the game, you can use the “Build Stand-Alone Game From File...” menu option. (In this case, MaxZip will quit after building the stand-alone game.)
• You will then see a standard Mac save dialog, with one addition: a text field for you to enter a creator code for your new game. This is a four-character code which the Mac uses to identify an application and its files. The only restriction is that it must contain at least one capital letter; the rest may be anything, including accented and other symbols.
• If you choose a creator code which is already used by some application on your Mac, you will receive a warning dialog. You should pick another one -- unless, of course, the conflict is with an earlier version of your own stand-alone game. (MaxZip attempts to detect this case so that it can skip the warning, but it doesn't always work.)
• MaxZip will build the new application.
You can use the new application immediately, but there are some things you can do with ResEdit to make it cuter. Always work on the new application -- please don't edit the MaxZip application. And remember to make a back-up before you use ResEdit.
• You can edit the icons for the application ('APPL', icon family 128) and its save files ('IFZS', icon family 129). If you do this, you will probably have to rebuild your desktop database before the new icons become visible. (To rebuild the desktop, restart your Mac and hold down command-option as it starts up.)
• You can edit 'vers' resource 1, to put in your name, your game's name, and your game's version. This information appears when someone does “Get Info” (cmd-I) on your game from the Finder. Do not change 'vers' resource 2; that contains the MaxZip version number and the message “Created by MaxZip”.
• For that matter, don't touch any other resources, even the strings that say “MaxZip”. Those resources are not just used for your game; they are copied into any unbound MaxZip apps your users make, and any stand-alone games they may make from that. Be courteous.
• If you are planning to widely distribute your stand-alone game (as opposed to just building one for your own convenience), you should register the creator code with Apple. Write to Developer Support Center, attn: C/F Type Administrator, 20525 Mariani Ave M/S 303-2T, Cupertino, CA 95014, USA. Include your name, address, phone, email, the creator code, and the game name.
◊ PowerMac and 68K concerns
MaxZip is a fat binary. This means that any stand-alone games you make will be fat as well.
This is a fairly hefty size increase. Therefore, you may want to use some kind of fat-stripping utility to remove either the PPC or 68K code from MaxZip or stand-alones. This will reduce the file size by 100K or more.
Stripped MaxZip executables should behave sensibly. That is, if you strip the PPC code from MaxZip, you'll get a 68K-only version; and any stand-alone games you produce from it will also be 68K-only, and any unbound MaxZips that anyone generates from those... etc. And the same for PPC-only versions. Your milage may vary, of course, depending on what stripping utility you use.
I would prefer that only complete, fat versions of MaxZip be distributed (but I'm not going to insist on it.) Similarly, I'd prefer that if you distribute a stand-alone MaxZip game, you distribute a fat version. I can hardly insist on that, either, but I think it makes sense.
◊ Known bugs
• In the save-game dialog, clicking in the “Annotation” box is screwed up. It sometimes leaves vertical lines, or fails to select text properly. Use the arrow keys or the Tab key to select the text, if necessary.
• The custom of triple-clicking to select a line of text is not supported.
• If you change the fixed-width font size, the status window does not adjust to fit. (You can click the zoom button twice to adjust it manually.)
• If you change the input style preference, the input style doesn't actually change until the next time you hit Enter.
• Controls in the preferences window do not dim when another window is in front.
◊ Version history
• Version 1.7.7:
Fixed a bug that could possibly cause a crash on exit.
Changed the set_font opcode to follow the current Z-Spec, and store 0 if the font is not available.
• Version 1.7.6:
Changed the extended-restore opcode so that loading a file which is too short doesn't produce an error.
• Version 1.7.5:
Fixed a bug that caused crashes after a “save”, “restore”, “save” sequence (reported for Infocom V3 games).
Fixed transcripting and recording (garbage would appear after command inputs in V5/8 games).
Added nested @output_stream 3 capacity, as per Z-Spec 1.0.
Arrow keys return the right codes to the game.
• Version 1.7.4:
Added stricter checking for Z-code errors, with a preference to control how they're reported.
Fixed a very silly bug which prevented save/restore in release 6 of any game.
• Version 1.7.2:
Fixed a problem with color opcodes halting the interpreter.
• Version 1.7.1:
You can now save a short comment with your saved games.
Fixed a bug which was causing “You don't see that here” messages.
• Version 1.7.0:
Added the extended save/restore opcodes, which allow games to save data files.
You can now use cmd-period to kill the interpreter, if a game goes into an infinite loop.
Added recording and playback of command sequences.
You can now turn on scripting twice, or append to an existing file. (Although the file dialog misleadingly asks you to "replace" the file.)
Save files are now in Quetzal format. (File type 'IFZS'.) This means they're portable to other machines, and smaller. Unfortunately, old-style saved games are no longer readable.
• Version 1.6.0:
Fixed all the header bit bugs; MaxZip now announces its capabilities correctly.
Fixed bug with preloaded input lines.
• Version 1.5.3:
Made more stable on old black-and-white Macs and PowerBooks.
• Version 1.5.2:
Numerous small display bugs which nobody ever reported before.
• Version 1.5.1:
Support for accented and other international characters — contributed by Tom Emerson (tree@apple.com).
Fixed signed division and modulo bug.
• Version 1.5.0:
Macros, hallelujah.
Fixed a crash-on-quit bug.
Still haven't gotten full PICKLE support.
• Version 1.4.9:
Partial PICKLE support. MaxZip can play PICKLE files, but not create stand-alone games from them.
The zoom button on the story window works now.
• Version 1.4.0:
Changed to correct implementation of the timed-input opcodes.
Added standard cursors (the I-beam cursor in the text area; the watch cursor during long operations.)
Made the behavior of paste correct for Macintosh applications.
Fixed bug in creating stand-alone games on 68K machines.
• Version 1.3.0:
Fat binary!
Added a check for files which have been downloaded in text mode (high-bit stripped.)
Fixed a few bugs with the clipboard. You can now copy from paused or menu screens; copying multiple lines works right; and copied text is not lost if MaxZip exits.
Fixed the truly unpleasant flicker you used to get when starting up.
The cursor blinks properly when in the status window.
• Version 1.2.1:
Fixed another display bug (very occasionally, the prompt line would disappear.) Also got the top/bottom margin preference to work.
• Version 1.2.0:
Added support for Inform's version-8 Z-code format. (MaxZip tries to accept V7 and V6 as well, but they may not work. Only V3, V5, and V8 are truly supported.)
Fixed some bugs with reverse-video text.
Made the filetype options in the "Import Z-Code" dialog more sensible.
• Version 1.1.0: First general release
Color preferences added
Scrolling is now smooth, without flicker
Status window position is saved in preferences
Fatal errors from the interpreter are displayed properly
Version number displayed initially in the message line is correct
Fixed small bug with positioning windows on multi-screen Macs
• Version 1.0.0: Preliminary release
◊ Permissions
Mac interface by Andrew Plotkin (erkyrath@netcom.com)
The Z-code engine is taken from ZIP V2.0.7 by Mark Howell (howell_ma@movies.enet.dec.com)
You are expressly forbidden to use this program on an Infocom game data file if, in so doing, you violate the copyright notice supplied with the original Infocom game.
Parts of this program are copyright 1995-9 by Andrew Plotkin. I do not know the exact copyright status of the rest, except that it was written by Mark Howell and thus is probably copyrighted by him. He released it for free, so to the best of my knowledge, the entirety of the unbound MaxZip application can be distributed and used freely, with the exception noted above.
If you build a stand-alone MaxZip game with a Z-code file you wrote, you own the stand-alone game. You may impose any restrictions or conditions you want on its use, and you may distribute it any way you want, including commercially. However, you may not interfere with the user's right or ability to build an unbound MaxZip application from your stand-alone game.
